---
title: Comments
description: Add comments to text as marks.
docs:
  - route: /docs/components/comment-leaf
    title: Comment Leaf
  - route: /docs/components/comment-toolbar-button
    title: Comment Toolbar Button
  - route: /docs/components/comments-popover
    title: Comments Popover
---

<ComponentPreview name="playground-demo" id="comment" />

<PackageInfo>

## Features

- Add text comments as marks.
- Comments can include explanations, suggestions, questions, notes, or ideas for content improvement.
- Add a comment by selecting the text and using the comment button or hotkey **`Cmd+Shift+M`**.

</PackageInfo>

## Installation

```bash
npm install @udecode/plate-comments
```

## Usage

```tsx
import { CommentsPlugin } from '@udecode/plate-comments/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CommentsPlugin,
  ],
});
```

## Keyboard Shortcuts

<KeyTable>
  <KeyTableItem hotkey="Cmd + Shift + M">
    Add a comment on the selected text.
  </KeyTableItem>
</KeyTable>

## Plugins

### CommentsPlugin

<APIOptions>

<APIItem name="newText" type="string">
The text for a new comment.
</APIItem>

<APIItem name="myUser" type="CommentUser">
The current user's information.
</APIItem>

<APIItem name="userById" type="(id: string) => CommentUser">
Function to get a user by their ID.
</APIItem>

<APIItem name="commentById" type="(id: string) => TComment">
Function to get a comment by its ID.
</APIItem>

<APIItem name="activeComment" type="TComment">
The currently active comment.
</APIItem>

</APIOptions>

## API

### editor.insert.comment

Insert a new comment mark.

### editor.api.comment.updateComment

Updates an existing comment.

### editor.api.comment.addRawComment

Adds a new raw comment.

### editor.api.comment.addComment

Adds a new comment.

### editor.api.comment.removeComment

Removes a comment.

### editor.api.comment.resetNewCommentValue

Resets the value of a new comment.

### CommentStoreState

<APIState>
  <APIItem name="id" type="string">
    The unique ID of the comment.
  </APIItem>
  <APIItem name="isMenuOpen" type="boolean">
    A flag indicating whether the menu associated with this comment is currently
    open.
  </APIItem>
  <APIItem name="editingValue" type="Value | null">
    The value currently being edited for this comment. If no editing is in
    progress, this value is null.
  </APIItem>
</APIState>

### findCommentNode

Finds the comment node in the editor.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="options" type="FindNodeOptions" optional>
    Additional options for finding the node.
  </APIItem>
</APIParameters>

### findCommentNodeById

Finds the comment node in the editor by its ID.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="id" type="string">
    The ID of the comment node to find.
  </APIItem>
</APIParameters>

### getCommentCount

Gets the count of comments in a comment node.

<APIParameters>
  <APIItem name="node" type="TCommentText">
    The comment node.
  </APIItem>
</APIParameters>

### getCommentKey

Generates a comment key based on the provided ID.

<APIParameters>
  <APIItem name="id" type="string">
    The ID of the comment.
  </APIItem>
</APIParameters>

### getCommentKeyId

Extracts the comment ID from a comment key.

<APIParameters>
  <APIItem name="key" type="string">
    The comment key.
  </APIItem>
</APIParameters>

### getCommentKeys

Returns an array of comment keys present in the given node.

<APIParameters>
  <APIItem name="node" type="TCommentText">
    The node to check for comment keys.
  </APIItem>
</APIParameters>

### getCommentNodeEntries

Returns an array of node entries for comment nodes in the editor.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
</APIParameters>

### getCommentNodesById

Returns an array of node entries for comment nodes with a specific ID in the editor.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="id" type="string">
    The ID of the comment nodes to retrieve.
  </APIItem>
</APIParameters>

### getCommentPosition

Calculates the position of a comment node relative to the editor.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="node" type="TCommentText">
    The comment node for which to calculate the position.
  </APIItem>
</APIParameters>

### getCommentUrl

Generates a URL with a query parameter for a specific comment ID.

<APIParameters>
  <APIItem name="commentId" type="string">
    The ID of the comment.
  </APIItem>
</APIParameters>

### getElementAbsolutePosition

Calculates the absolute position of an HTML element relative to the document.

<APIParameters>
  <APIItem name="element" type="HTMLElement">
    The HTML element for which to calculate the absolute position.
  </APIItem>
</APIParameters>

### isCommentKey

Checks if a given key is a comment key.

<APIParameters>
  <APIItem name="key" type="string">
    The key to check.
  </APIItem>
</APIParameters>

### isCommentNodeById

Checks if a given node is a comment with the specified ID.

<APIParameters>
  <APIItem name="node" type="TNode">
    The node to check.
  </APIItem>
  <APIItem name="id" type="string">
    The ID of the comment.
  </APIItem>
</APIParameters>

### isCommentText

Checks if a given node is a comment text node.

<APIParameters>
  <APIItem name="node" type="TNode">
    The node to check.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="boolean">`true` if the node is a comment text node.</APIItem>
</APIReturns>

### removeCommentMark

Removes the comment mark from the editor.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
</APIParameters>

### unsetCommentNodesById

Unsets comment nodes with the specified ID from the editor.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="id" type="string">
    The ID of the comment nodes to unset.
  </APIItem>
</APIParameters>

### CommentUser

An interface representing a user who can make comments.

<APIParameters>
  <APIItem name="id" type="string">
    The unique ID of the user.
  </APIItem>
  <APIItem name="name" type="string">
    The name of the user.
  </APIItem>
  <APIItem name="avatarUrl" type="string" optional>
    The URL of the user's avatar.
  </APIItem>
</APIParameters>

### TComment

<APIAttributes>
<APIItem name="id" type="string">
A unique ID for the comment.
</APIItem>
<APIItem name="value" type="Value">
The Slate value of the comment.
</APIItem>
<APIItem name="createdAt" type="number">
Timestamp when the comment was created.

- **Default:** `Date.now()`

</APIItem>
<APIItem name="userId" type="string">
Id of the author of the comment.
</APIItem>
<APIItem name="parentId" type="string" optional>
Id of the parent comment it replies to.
</APIItem>
<APIItem name="isResolved" type="boolean" optional>
Whether the comment is resolved.
</APIItem>
</APIAttributes>

### TCommentText

<APIAttributes>
  <APIItem name="comment_<id>" type="boolean" optional>
    Indicates whether this is a comment. Multiple comments can be present in a
    single text node.
  </APIItem>
</APIAttributes>

## API Components

### CommentProvider

A jotai provider for comment data.

<APIProps>
  Extends `CommentStoreState`.

  <APIItem name="scope" type="Scope" optional>
    The scope of the provider.
  </APIItem>
</APIProps>

### CommentDeleteButton

A button component for deleting a comment.

<APIState>
  <APIItem name="activeCommentId" type="string">
    The ID of the active comment.
  </APIItem>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="id" type="string">
    The ID of the comment.
  </APIItem>
  <APIItem name="onCommentDelete" type="function">
    A function to call when the comment is deleted.
  </APIItem>
  <APIItem name="removeComment" type="function">
    A function to remove the comment.
  </APIItem>
  <APIItem name="setActiveCommentId" type="function">
    A function to set the active comment ID.
  </APIItem>
</APIState>

### CommentEditButton

A button component for editing a comment.

<APIState>
  <APIItem name="setIsMenuOpen" type="function">
    A function to set the menu open state.
  </APIItem>
  <APIItem name="comment" type="TComment">
    The comment object.
  </APIItem>
  <APIItem name="editingValue" type="function">
    A function to set the editing value.
  </APIItem>
</APIState>

### CommentEditCancelButton

A button component for canceling the editing of a comment.

### CommentEditSaveButton

A button component for saving the editing of a comment.

<APIState>
  <APIItem name="editingValue" type="Value">
    The value of the editing value.
  </APIItem>
  <APIItem name="setEditingValue" type="function">
    A function to set the editing value.
  </APIItem>
  <APIItem name="id" type="string">
    The ID of the comment.
  </APIItem>
  <APIItem name="onCommentUpdate" type="function">
    A function to call when the comment is updated.
  </APIItem>
  <APIItem name="updateComment" type="function">
    A function to update the comment.
  </APIItem>
  <APIItem name="value" type="string">
    The value of the comment.
  </APIItem>
</APIState>

### CommentEditTextarea

A textarea component for editing a comment.

<APIState>
  <APIItem name="setEditingValue" type="function">
    A function to set the editing value.
  </APIItem>
  <APIItem name="textareaRef" type="React.Ref">
    The textarea ref.
  </APIItem>
  <APIItem name="value" type="string">
    The value of the textarea.
  </APIItem>
</APIState>

### CommentNewSubmitButton

A button component for submitting a new comment.

<APIState>
  <APIItem name="editingCommentText" type="string">
    The text of the comment being edited.
  </APIItem>
  <APIItem name="resetNewCommentValue" type="function">
    A function to reset the new comment value.
  </APIItem>
  <APIItem name="addComment" type="function">
    A function to add a comment.
  </APIItem>
  <APIItem name="isReplyComment" type="boolean">
    Whether the comment is a reply.
  </APIItem>
  <APIItem name="submitButtonText" type="string">
    The text of the submit button.
  </APIItem>
  <APIItem name="onCommentAdd" type="function">
    A function to call when the comment is added.
  </APIItem>
  <APIItem name="activeCommentId" type="string">
    The ID of the active comment.
  </APIItem>
  <APIItem name="comment" type="TComment">
    The comment object.
  </APIItem>
  <APIItem name="newValue" type="Value">
    The value of the edited comment.
  </APIItem>
</APIState>

### CommentNewTextarea

A textarea component for adding a new comment.

<APIState>
  <APIItem name="textareaRef" type="React.Ref">
    The textarea ref.
  </APIItem>
  <APIItem name="placeholder" type="string">
    The placeholder of the textarea.
  </APIItem>
  <APIItem name="value" type="string">
    The value of the textarea.
  </APIItem>
  <APIItem name="setNewValue" type="function">
    A function to set the new value.
  </APIItem>
</APIState>

### CommentResolveButton

A button component for resolving/unresolving a comment.

### CommentUserName

A div component for displaying the name of a comment user.

### CommentsPositioner

A div component for positioning comments in the editor.

<APIState>
  <APIItem name="activeCommentId" type="string">
    The ID for the active comment.
  </APIItem>
  <APIItem name="position" type="object">
    An object representing the current position of the comment (top and left
    coordinates).
  </APIItem>
</APIState>

### useActiveCommentNode

A custom hook that retrieves the active comment node based on the active comment ID.

<APIReturns>

- If there is an active comment ID, it returns the corresponding comment node.

- If there is no active comment ID or the comment node is not found, it returns `null`.

</APIReturns>

### useCommentAddButton

A custom hook that provides functionality for adding a comment mark to the selected text and setting focus to the comment textarea.

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem parent="props" name="onClick" type="function">
        A function to call when the button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>

### useCommentItemContentState

A state hook for the comment item content component.

<APIReturns>
  <APIItem name="comment" type="TComment">
    The comment object.
  </APIItem>
  <APIItem name="isReplyComment" type="boolean">
    A boolean indicating whether the comment is a reply comment.
  </APIItem>
  <APIItem name="commentText" type="string">
    The text content of the comment.
  </APIItem>
  <APIItem name="user" type="CommentUser">
    The user associated with the comment.
  </APIItem>
  <APIItem name="myUserId" type="string">
    The ID of the current user.
  </APIItem>
  <APIItem name="editingValue" type="Value">
    The value of the comment being edited.
  </APIItem>
  <APIItem name="isMyComment" type="boolean">
    A boolean indicating whether the comment is authored by the current user.
  </APIItem>
</APIReturns>

### useCommentLeaf

A behavior hook for the comment leaf component.

<APIParameters>
  <APIItem name="setActiveCommentId" type="function">
    The function to set the active comment ID.
  </APIItem>
  <APIItem name="lastCommentId" type="string">
    The ID of the last comment in the leaf.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem parent="props" name="onClick" type="function">
        A function to call when the button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>

### useCommentValue

A custom hook that focuses and selects the text inside a textarea.

<APIReturns>
  <APIItem name="textareaRef" type="React.Ref">
    A ref to the textarea element.
  </APIItem>
</APIReturns>

### useCommentsResolved

A custom hook that returns an array of resolved comments.

<APIReturns>
<APIItem type="TComment[]">

An array of resolved comments.

</APIItem>
</APIReturns>

### useCommentsShowResolvedButton

A custom hook that returns the props for a button component used to show resolved comments.

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem parent="props" name="pressed" type="boolean">
        A boolean indicating whether the button is pressed.
      </APISubListItem>
      <APISubListItem parent="props" name="onClick" type="function">
        A function to call when the button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>